<!DOCTYPE html>
<html>
  <head>
    <meta charset='utf-8'>
    <meta content='width=device-width, initial-scale=1.0' name='viewport'>
    <meta content='' name='description'>
    <meta content='Nils Nordman' name='author'>
    <link href='/images/howl.png' rel='shortcut icon'>
    <title>Howl :: Configuring Howl</title>
    <link href="/stylesheets/bootstrap.min.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/syntax.css" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/howl.css" media="screen" rel="stylesheet" type="text/css" />
    <script src="https://code.jquery.com/jquery-1.12.3.min.js" type="text/javascript"></script>
    <script src="/javascripts/bootstrap.min.js" type="text/javascript"></script>
    <script src="/javascripts/manual.js" type="text/javascript"></script>
    <link href='//fonts.googleapis.com/css?family=Josefin+Slab' rel='stylesheet' type='text/css'>
    <link href='//fonts.googleapis.com/css?family=Open+Sans+Condensed:700' rel='stylesheet' type='text/css'>
  </head>
  <body class='doc doc_manual doc_manual_configuration'>
    <div class='container'>
      <div class='masthead'>
        <ul class='nav nav-pills'>
          <li>
            <a href='/'>
              <span class='glyphicon glyphicon-home'></span>
              Home
            </a>
          </li>
          <li>
            <a href='/doc/'>
              <span class='glyphicon glyphicon-book'></span>
              Documentation
            </a>
          </li>
          <li>
            <a href='/blog/'>
              <span class='glyphicon glyphicon-bullhorn'></span>
              Blog
            </a>
          </li>
          <li>
            <a href='/contact.html'>
              <span class='glyphicon glyphicon-inbox'></span>
              Contact
            </a>
          </li>
        </ul>
      </div>
      <ol class="breadcrumb"><li><a href="/">Home</a></li><li><a href='../'>Howl 0.4 Documentation</a></li><li>Manual</li><li>Configuring Howl</li></ol>
      <div class='howl-theme-selector' style='display:none'>&#x000A;  <div class='dropdown'>&#x000A;    <button class='btn btn-default btn-sm' data-toggle='dropdown' type='button'>&#x000A;      Select theme for pictures..&#x000A;      <b class='caret'></b>&#x000A;    </button>&#x000A;    <ul class='dropdown-menu' role='menu'>&#x000A;      <li role='presentation'>&#x000A;        <a class='set-howl-theme' data-key='monokai' href='#' role='menuitem'>&#x000A;          Monokai&#x000A;        </a>&#x000A;      </li>&#x000A;      <li role='presentation'>&#x000A;        <a class='set-howl-theme' data-key='solarized-light' href='#' role='menuitem'>&#x000A;          Solarized Light&#x000A;        </a>&#x000A;      </li>&#x000A;      <li role='presentation'>&#x000A;        <a class='set-howl-theme' data-key='steinom' href='#' role='menuitem'>&#x000A;          Steinom&#x000A;        </a>&#x000A;      </li>&#x000A;      <li role='presentation'>&#x000A;        <a class='set-howl-theme' data-key='tomorrow-night-blue' href='#' role='menuitem'>&#x000A;          Tomorrow Night Blue&#x000A;        </a>&#x000A;      </li>&#x000A;    </ul>&#x000A;  </div>&#x000A;</div>&#x000A;<h1 id="configuring-howl">Configuring Howl</h1>    <div class="toc">
      <div class="toc-title">
        <span>Configuring Howl</span>
      </div>
      <div class="toc-entries">
<div class="toc-group">
<a href="#init-files" class="toc-group-header init_files">Init files</a>
</div>
<div class="toc-group">
<a href="#configuration-variables" class="toc-group-header configuration_variables">Configuration variables</a>
<li class=""><a href="#overview">Overview</a></li>
<li class=""><a href="#programmatic-access">Programmatic access</a></li>
<li class=""><a href="#setting-variables-upon-startup">Setting variables upon startup</a></li>
</div>
<div class="toc-group">
<a href="#key-bindings" class="toc-group-header key_bindings">Key bindings</a>
</div>
<div class="toc-group">
<a href="#running-commands" class="toc-group-header running_commands">Running commands</a>
</div>
</div>
</div>
&#x000A;&#x000A;<h2 id="init-files">Init files</h2>&#x000A;&#x000A;<p>Howl looks for a startup file in the Howl <em>user directory</em>: <code>~/.howl</code>. It&#x000A;searches for either <code>~/.howl/init.lua</code> or <code>~/.howl/init.moon</code>. Which one&#x000A;to pick depends on your preference with regards to language - <code>init.moon</code>&#x000A;for <a href="http://moonscript.org">Moonscript</a> and <code>init.lua</code> for&#x000A;<a href="http://www.lua.org">Lua</a>. Should a startup file be found, it is loaded&#x000A;after Howl is initialized, which includes loading all available bundles.&#x000A;Howl does not have any special configuration format for use with the&#x000A;startup file, instead it&rsquo;s just plain Lua or Moonscript. While the startup&#x000A;file would typically be mostly used for various type of configuration,&#x000A;there&rsquo;s no restriction to what you can do in it - you have access to the entire&#x000A;<a href="../#api-reference">Howl API</a>.</p>&#x000A;&#x000A;<p>You can split up your startup code in multiple files if you like. Your local&#x000A;user files will be not found by an ordinary <code>require</code>, since the user directory&#x000A;is not part of the search path. However, there is an <code>user_load</code> helper available&#x000A;from your startup files that works the same way. For example, given&#x000A;<code>init.moon</code> and <code>other.moon</code> in the Howl user directory, you could load&#x000A;&lsquo;other&rsquo; from init like so:</p>&#x000A;<pre class="highlight moonscript"><span class="n">other</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">user_load</span><span class="w"> </span><span class="s1">'other'</span><span class="w">&#x000A;</span></pre>&#x000A;<p>Just as with <code>require</code>, paths are given without any extension. Files are&#x000A;loaded only once, with subsequent loads returning the same value. The path&#x000A;passed to <code>user_load</code> can contain dots, which are translated to the directory&#x000A;separator before loading the file.</p>&#x000A;&#x000A;<p>It is not allowed for the startup files to implicitly clobber the global&#x000A;environment, and Howl will raise an error upon startup if this is detected.&#x000A;Consider for instance this incorrect Lua startup file:</p>&#x000A;<pre class="highlight lua"><span class="c1">-- Oops, forgot the local keyword here</span>&#x000A;<span class="n">my_internal_var</span> <span class="o">=</span> <span class="mi">2</span>&#x000A;</pre>&#x000A;<p>This would cause Howl to abort with an error upon startup. Should you for any&#x000A;reason want to set a global variable, you can do so by being explicit:</p>&#x000A;<pre class="highlight lua"><span class="n">_G</span><span class="p">.</span><span class="n">my_explicit_global</span> <span class="o">=</span> <span class="mi">2</span>&#x000A;</pre>&#x000A;<p>(<em>Note</em>: the <code>user_load</code> helper is only available when loading startup files.)</p>&#x000A;&#x000A;<h2 id="configuration-variables">Configuration variables</h2>&#x000A;&#x000A;<h3 id="overview">Overview</h3>&#x000A;&#x000A;<p>Things that are meant to be configurable in Howl are exposed as &ldquo;configuration&#x000A;variables&rdquo;. Configuration variables can be set either interactively from within&#x000A;Howl, using the <code>set</code> command, or programmatically from code. To get an overview&#x000A;of currently available variables, type <code>set</code> and press <code>space</code> at the command&#x000A;line to view a list.</p>&#x000A;&#x000A;<p>Configuration variables can be specified at three different levels in Howl,&#x000A;in ascending order of priority:</p>&#x000A;&#x000A;<ul>&#x000A;<li><em>Globally</em></li>&#x000A;</ul>&#x000A;&#x000A;<p>The value set for the variable is used unless overridden by a mode or buffer&#x000A;specific setting (the <code>set</code> command always sets variables globally).</p>&#x000A;&#x000A;<ul>&#x000A;<li><em>Per mode</em></li>&#x000A;</ul>&#x000A;&#x000A;<p>The value is set for a particular mode (e.g. &ldquo;Lua&rdquo; or &ldquo;Ruby&rdquo;), and is applied&#x000A;whenever a buffer with that particular mode is active. The value is used unless&#x000A;overridden by a buffer specific setting, and overrides any global setting.</p>&#x000A;&#x000A;<ul>&#x000A;<li><em>Per buffer</em></li>&#x000A;</ul>&#x000A;&#x000A;<p>The value is set for a particular buffer, and is applied whenever that buffer&#x000A;is active. The value overrides any mode specific or global setting.</p>&#x000A;&#x000A;<p>As an example of how this could be used a real life scenario, consider the&#x000A;case of indentation: You might generally prefer your source code to be indented&#x000A;with two spaces. However, some languages might have generally accepted style&#x000A;guidelines where four spaces is considered the norm. Even so, certain projects&#x000A;written in such a language might have adopted the inexplicable custom of using&#x000A;three spaces for indentation.</p>&#x000A;&#x000A;<p>In such a scenario, you could set the <code>indent</code> variable to 2 globally, override&#x000A;it with 4 for a given mode, and override with 3 for any buffer with an associated&#x000A;file in a certain directory.</p>&#x000A;&#x000A;<h3 id="programmatic-access">Programmatic access</h3>&#x000A;&#x000A;<p>As described above, variables can be set on three different levels. No matter&#x000A;the on what level they&rsquo;re set, they&rsquo;re always set (and accessed) using&#x000A;<code>config</code> objects. For global accesses, you can use the main config object in&#x000A;the howl namespace. For mode variables you access variables using the config&#x000A;object on a particular mode instance, and similarily for buffer variables&#x000A;you use the config object for a particular buffer.</p>&#x000A;&#x000A;<p>The following code snippet illustrates the various ways of setting variables on&#x000A;different levels:</p>&#x000A;<pre class="highlight lua"><span class="n">howl</span><span class="p">.</span><span class="n">config</span><span class="p">.</span><span class="n">my_var</span> <span class="o">=</span> <span class="s1">'foo'</span>&#x000A;<span class="n">howl</span><span class="p">.</span><span class="n">mode</span><span class="p">.</span><span class="n">by_name</span><span class="p">(</span><span class="s1">'ruby'</span><span class="p">).</span><span class="n">config</span><span class="p">.</span><span class="n">my_var</span> <span class="o">=</span> <span class="s1">'foo'</span>&#x000A;<span class="n">howl</span><span class="p">.</span><span class="n">app</span><span class="p">:</span><span class="n">new_buffer</span><span class="p">().</span><span class="n">config</span><span class="p">.</span><span class="n">my_var</span> <span class="o">=</span> <span class="s1">'foo'</span>&#x000A;</pre>&#x000A;<h3 id="setting-variables-upon-startup">Setting variables upon startup</h3>&#x000A;&#x000A;<p>Let&rsquo;s have a look at configuring the <code>indent</code> variable as discussed in the&#x000A;<a href="#overview">overview</a>, using the below example Moonscript init file (init.moon):</p>&#x000A;<pre class="highlight moonscript"><span class="k">import</span><span class="w"> </span><span class="n">config</span><span class="p">,</span><span class="w"> </span><span class="n">mode</span><span class="p">,</span><span class="w"> </span><span class="n">signal</span><span class="w"> </span><span class="n">from</span><span class="w"> </span><span class="n">howl</span><span class="w">&#x000A;</span><span class="k">import</span><span class="w"> </span><span class="nc">File</span><span class="w"> </span><span class="n">from</span><span class="w"> </span><span class="n">howl</span><span class="p">.</span><span class="n">fs</span><span class="w">&#x000A;&#x000A;</span><span class="c1">-- Set indent globally to two spaces</span><span class="w">&#x000A;</span><span class="n">config</span><span class="p">.</span><span class="n">indent</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">2</span><span class="w">&#x000A;&#x000A;</span><span class="c1">-- Use four spaces for C files</span><span class="w">&#x000A;</span><span class="n">mode</span><span class="p">.</span><span class="n">configure</span><span class="w"> </span><span class="s1">'c'</span><span class="p">,</span><span class="w"> </span><span class="p">{</span><span class="w">&#x000A;  </span><span class="ss">indent:</span><span class="w"> </span><span class="mi">4</span><span class="w">&#x000A;</span><span class="p">}</span><span class="w">&#x000A;&#x000A;</span><span class="c1">-- Hook up a signal handler to set it to three for this weird project</span><span class="w">&#x000A;</span><span class="n">that_project_root</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nc">File</span><span class="w"> </span><span class="s1">'/home/nino/code/that_project'</span><span class="w">&#x000A;&#x000A;</span><span class="n">signal</span><span class="p">.</span><span class="n">connect</span><span class="w"> </span><span class="s1">'file-opened'</span><span class="p">,</span><span class="w"> </span><span class="p">(</span><span class="n">args</span><span class="p">)</span><span class="w"> </span><span class="o">-&gt;</span><span class="w">&#x000A;  </span><span class="k">if</span><span class="w"> </span><span class="n">args</span><span class="p">.</span><span class="n">file</span><span class="o">\</span><span class="n">is_below</span><span class="w"> </span><span class="n">that_project_root</span><span class="w">&#x000A;    </span><span class="n">args</span><span class="p">.</span><span class="n">buffer</span><span class="p">.</span><span class="n">config</span><span class="p">.</span><span class="n">indent</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">3</span><span class="w">&#x000A;</span></pre>&#x000A;<p>A few notes on the above example:</p>&#x000A;&#x000A;<ul>&#x000A;<li><p>There&rsquo;s no need to <code>require</code> any class/module/etc. that comes with Howl.&#x000A;They&rsquo;re all available upon access. You can still require them&#x000A;explicitly if you want to however.</p></li>&#x000A;<li><p>We use <a href="../api/mode.html#configure">mode.configure</a> for specifying the mode&#x000A;variable rather than setting it using the config object of an existing mode&#x000A;instance. This is because we don&rsquo;t want to load the mode unnecessarily just&#x000A;to set a variable. Using configure() instead means that it will be set once&#x000A;the mode is loaded (or straight away should the mode already be loaded).</p></li>&#x000A;<li><p>We use <a href="../api/signal.html#connect">signal.connect</a> to add a signal handler&#x000A;for the <code>file-opened</code> signal, and set the indent for a certain buffer with&#x000A;an associated file under a given directory.</p></li>&#x000A;</ul>&#x000A;&#x000A;<h2 id="key-bindings">Key bindings</h2>&#x000A;&#x000A;<p>Key bindings map keyboard presses to different actions within Howl. The&#x000A;nitty-gritty details on how this is handled is outlined in the documentation&#x000A;for the <a href="../api/bindings.html">bindings module</a>, and won&rsquo;t be repeated here.&#x000A;Rather, the below Lua example illustrates how to add different kind of binding&#x000A;customizations from within your init file (init.lua).</p>&#x000A;<pre class="highlight lua"><span class="n">howl</span><span class="p">.</span><span class="n">bindings</span><span class="p">.</span><span class="n">push</span> <span class="p">{</span>&#x000A;  <span class="c1">-- editor specific bindings</span>&#x000A;  <span class="n">editor</span> <span class="o">=</span> <span class="p">{</span>&#x000A;    <span class="c1">-- bind ctrl_k to a named command</span>&#x000A;    <span class="n">ctrl_k</span> <span class="o">=</span> <span class="s1">'editor-cut-to-end-of-line'</span><span class="p">,</span>&#x000A;&#x000A;    <span class="c1">-- bind ctrl_shift_x to a closure</span>&#x000A;    <span class="n">ctrl_shift_x</span> <span class="o">=</span> <span class="k">function</span><span class="p">(</span><span class="n">editor</span><span class="p">)</span>&#x000A;      <span class="c1">-- replace the active chunk with a reversed bracked enclosed version</span>&#x000A;      <span class="n">editor</span><span class="p">.</span><span class="n">active_chunk</span><span class="p">.</span><span class="n">text</span> <span class="o">=</span> <span class="s2">"&lt;"</span> <span class="o">..</span> <span class="n">editor</span><span class="p">.</span><span class="n">active_chunk</span><span class="p">.</span><span class="n">text</span><span class="p">.</span><span class="n">ureverse</span> <span class="o">..</span> <span class="s2">"&gt;"</span>&#x000A;    <span class="k">end</span>&#x000A;  <span class="p">},</span>&#x000A;&#x000A;  <span class="c1">-- Bind the Emacs find-file binding (C-x C-f) to the open command</span>&#x000A;  <span class="n">ctrl_x</span> <span class="o">=</span> <span class="p">{</span>&#x000A;    <span class="n">ctrl_f</span> <span class="o">=</span> <span class="s1">'open'</span>&#x000A;  <span class="p">}</span>&#x000A;<span class="p">}</span>&#x000A;</pre>&#x000A;<h2 id="running-commands">Running commands</h2>&#x000A;&#x000A;<p>You&rsquo;ve seen how to invoke commands from a key binding (simply specify the&#x000A;command name as a string), but sometimes you&rsquo;ll want to invoke commands&#x000A;programmatically from within your startup file. As an example, to enter&#x000A;VI mode automatically upon startup:</p>&#x000A;<pre class="highlight moonscript"><span class="n">howl</span><span class="p">.</span><span class="n">command</span><span class="p">.</span><span class="n">vi_on</span><span class="o">!</span><span class="w">&#x000A;</span></pre>&#x000A;<p>Consult the documentation for the <a href="../api/command.html">command module</a> for more&#x000A;information.</p>&#x000A;&#x000A;<p><em>Next</em>: <a href="completions.html">Using Howl completions</a></p>
      <div class='footer text-muted'>
        <a href='/'>
          <img width="50" height="50" class="footer-logo" src="/images/howl.png" />
        </a>
        <div class='footer-follow'>
          <p>
            <a class='twitter-follow-button' data-lang='en' data-show-count='false' href='https://twitter.com/howleditor' rel='me'>
              Follow @howleditor
            </a>
          </p>
          <p>
            <a class='twitter-share-button' data-count='none' data-hashtags='howleditor' data-lang='en' data-text='The Howl Editor, a general purpose, light-weight customizable editor.' data-url='http://howl.io' href='https://twitter.com/share'>
              Tweet
            </a>
          </p>
        </div>
        <div class='footer-blurb'>
          <div>The Howl editor.</div>
          <div>
            Copyright 2012-2016
            <a class='alert-link' href='https://github.com/howl-editor/howl/contributors'>
              The Howl Developers.
            </a>
          </div>
        </div>
      </div>
    </div>
    <script>
      <!-- / GA -->
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
      })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
      ga('create', 'UA-45283282-1', 'howl.io');
      ga('send', 'pageview');
      <!-- / Twitter -->
      !function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];
      if(!d.getElementById(id)){js=d.createElement(s);js.id=id;
      js.src="//platform.twitter.com/widgets.js";
      fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
    </script>
  </body>
</html>

